home *** CD-ROM | disk | FTP | other *** search
/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / IDE / SUBARTIC / SUB_ARCT / INPUT / SINGLE_F.JAV < prev    next >
Encoding:
Text File  |  1996-10-04  |  5.6 KB  |  174 lines
  1.  
  2. package sub_arctic.input;
  3.  
  4. import sub_arctic.lib.sub_arctic_error;
  5.  
  6. import java.util.Vector;
  7.  
  8. /** 
  9.  * This is a subclass of focus_dispatch_agent designed to support agents
  10.  * which need to limit their focus set to at most one element.
  11.  *
  12.  * @author Scott Hudson
  13.  */
  14.  
  15. public abstract class single_focus_agent extends focus_dispatch_agent {
  16.  
  17.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  18.  
  19.   /** Simple constructor */
  20.   public single_focus_agent() 
  21.     {
  22.       /* reclaim extra space since we know we are not larger than 1 */
  23.       _focus_set.setSize(1);
  24.       _user_info_set.setSize(1);
  25.     }
  26.  
  27.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  28.  
  29.   /**
  30.    * Replace the focus set of this agent with the given object.  This provides
  31.    * a causal event and an uninterpreted object that will be passed back to
  32.    * the focus object whenever input is delivered to it by this agent.<p>
  33.    *
  34.    * @param focusable to_obj    the object going in the focus set.
  35.    * @param event     evt       the event that "caused" this focus.
  36.    * @param Object    user_info the uninterpreted information that we will pass
  37.    *                            back to the object whenever it gets input from
  38.    *                            this agent.
  39.    */
  40.   public void set_focus_to(focusable to_obj, event evt, Object user_info)
  41.     {
  42.       int       i;
  43.       focusable remove_obj;
  44.       Object    remove_info;
  45.       boolean   already_focus = false;
  46.  
  47.       /* make sure its ok to add */
  48.       if (!allowable_focus(to_obj))
  49.     throw new sub_arctic_error(
  50.       "Attempt to add an ineligible object to the focus set");
  51.  
  52.       /* if they set to a null focus, treat that as a clear */
  53.       if (to_obj == null)
  54.     {
  55.       clear_focus(evt);
  56.       return;
  57.     }
  58.  
  59.       /* pull out the old focus object */ 
  60.       remove_obj = (focusable)_focus_set.elementAt(0);
  61.       remove_info = _user_info_set.elementAt(0);
  62.  
  63.       /* we do something only if its a change */
  64.       if (to_obj != remove_obj)
  65.     {
  66.       /* inform the old object about loss of focus */
  67.       if (remove_obj != null) inform_focus_exit(remove_obj,evt,remove_info);
  68.  
  69.       /* put in the new object */
  70.       _focus_set.setElementAt(to_obj, 0);
  71.       _user_info_set.setElementAt(user_info, 0);
  72.  
  73.       /* tell it that it has the focus */
  74.       inform_focus_enter(to_obj,evt,user_info);
  75.     }
  76.     }
  77.  
  78.    //had:
  79.    //* @exception bad_value if this object is not suitable for inclusion in this
  80.    //*                      focus set.
  81.    //* @exception general
  82.  
  83.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  84.  
  85.   /** 
  86.    * Add object to focus set.  For this subclass this replaces the current
  87.    * focus hence acts the same as set_focus_to().
  88.    *
  89.    * @param focusable new_obj   the object going in the focus set.
  90.    * @param event     evt       the event that "caused" this focus.
  91.    * @param Object    user_info the uninterpreted information that we will pass
  92.    *                            back to the object whenever it gets input from
  93.    *                            this agent.
  94.    */
  95.   public void add_to_focus(focusable new_obj, event evt, Object user_info)
  96.     {
  97.       /* for singles this is the same as just setting the focus */
  98.       set_focus_to(new_obj, evt, user_info);
  99.     }
  100.  
  101.    //has:
  102.    //* @exception bad_value if this object is not suitable for inclusion in this
  103.    //*                      focus set.
  104.  
  105.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  106.  
  107.   /**
  108.    * Remove the given object from the focus set.  If the object is in the
  109.    * focus set this acts like clear_focus().  If not an exception is thrown.
  110.    *
  111.    * @param focusable obj the object going in the focus set.
  112.    * @param event     evt the event that "caused" this focus.
  113.    */
  114.   public void remove_from_focus(focusable obj, event evt)
  115.     {
  116.       Object user_info;
  117.  
  118.       /* if its not our focus we throw an exception */
  119.       if (obj != _focus_set.elementAt(0))
  120.     throw new sub_arctic_error(
  121.       "Attempt to remove focus from an object not in the focus set");
  122.  
  123.       /* otherwise remove it and let it know */
  124.       _focus_set.setElementAt(null, 0);
  125.       user_info = _user_info_set.elementAt(0);
  126.       _user_info_set.setElementAt(null, 0);
  127.       inform_focus_exit(obj, evt, user_info);
  128.     }
  129.  
  130.    //has:
  131.    //* @exception bad_value if this object is not in the focus set.
  132.  
  133.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  134.  
  135.   /** 
  136.    * Clear the focus set of this agent to empty.
  137.    * @param event evt the event that "caused" this.
  138.    */
  139.   public void clear_focus(event evt)
  140.     {
  141.       focusable old;
  142.       Object    old_info;
  143.  
  144.       /* pull out the old focus */
  145.       old      = (focusable)_focus_set.elementAt(0);
  146.       old_info = _user_info_set.elementAt(0);
  147.  
  148.       /* get rid of any focus */
  149.       _focus_set.setElementAt(null, 0);
  150.       _user_info_set.setElementAt(null, 0);
  151.  
  152.       /* if we really had an old focus let it now that its out. */
  153.       if (old != null) inform_focus_exit(old, evt, old_info);
  154.     }
  155.  
  156.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  157. }
  158. /*=========================== COPYRIGHT NOTICE ===========================
  159.  
  160. This file is part of the subArctic user interface toolkit.
  161.  
  162. Copyright (c) 1996 Scott Hudson and Ian Smith
  163. All rights reserved.
  164.  
  165. The subArctic system is freely available for most uses under the terms
  166. and conditions described in 
  167.   http://www.cc.gatech.edu/gvu/ui/sub_arctic/sub_arctic/doc/usage.html 
  168. and appearing in full in the lib/interactor.java source file.
  169.  
  170. The current release and additional information about this software can be 
  171. found starting at: http://www.cc.gatech.edu/gvu/ui/sub_arctic/
  172.  
  173. ========================================================================*/
  174.